Sets a group of color table entries for the current GDevice data structure. This function is used by system software and your application should not need to call it.

void SetEntries (
    SInt16 start, 
    SInt16 count, 
    CSpecArray aTable
);

Parameter descriptions

start

The index of the first entry to be changed.

count

The number of entries to be changed.Note that all values are zero-based; for example, to set three entries, pass 2 in the count parameter.

aTable

An array of ColorSpec data structures containing the colors to be used. Directly specify a cSpecArray structure, not the beginning of a color table.The ColorSpec.value fields of the entries must be in the logical range for the target device’s assigned pixel depth. Thus, with a 4-bit pixel size, the ColorSpec.value fields should be in the range 1 to 15. With an 8-bit pixel size, the range is 0 to 255.

DISCUSSION

Instead of using SetEntries, you should use the Palette Manager function SetEntryColor to allow your application to run in a multiscreen or multitasking environment.

The SetEntries positional information works in logical space rather than in the actual memory space used by the hardware. Requesting a change at the fourth position in the color table may not modify the fourth color table entry in the hardware, but it does correctly change the color on the screen for any pixels with a value of 4 in the video card. The SetEntries mode characterized by a start position and a length is called sequence mode. In this case, SetEntries sequentially loads new colors into the hardware in the same order as they appear in the aTable parameter, copies the clientID fields for changed color table entries from the current GDevice data structure’s gdID field, and ignores the ColorSpec.value fields.

The other SetEntries mode is called index mode. It allows the cSpecArray structure to specify where the data will be installed on an entry-by-entry basis. To use this mode, pass –1 for the start position, with a valid count and a pointer to the cSpecArray data structure. Each entry is installed into the color table at the position specified by the ColorSpec.value field of each entry in the cSpecArray data structure. In the current GDevice data structure’s color table, the ColorSpec.value fields of all changed entries are assigned the GDevice data structure’s gdID value.

When the Color Manager changes color table entries, it invalidates all cached fonts, and changes the color tables’s seed number so that the next drawing operation triggers the Color Manager to rebuild the inverse table. If any of the requested entries are protected or out of range, the Color Manager returns a protection error, and nothing happens. The Color Manager changes a reserved entry only if the current gdID field of the current GDevice data structure matches the low byte of the intended ColorSpec.value field in the color table.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)